Harness Engineering 深度笔记
我来为您整理这篇关于 Harness Engineering 的详尽笔记。
Harness Engineering 深度笔记
一、核心公式：Agent = Model + Harness
| 组件 | 定义 | 类比 |
|---|---|---|
| Model（模型） | 能力的来源，文本进文本出的函数 | CPU |
| Harness | 模型之外的一切——系统提示词、工具调用、文件系统、沙箱环境、编排逻辑、约束机制、反馈回路 | 操作系统 |
关键洞察：你不是模型，那你就是 Harness。模型决定了系统的上限，Harness 决定了系统的底线。
二、三层嵌套关系：Prompt ⊂ Context ⊂ Harness
| 层级 | 核心问题 | 关注点 | 典型工作 |
|---|---|---|---|
| Prompt Engineering | 表达——怎么写好指令 | 塑造局部概率空间，让模型听懂意图 | 系统提示词设计、Few-shot、思维链引导 |
| Context Engineering | 信息——给 Agent 看什么 | 确保模型在合适的时机拿到正确且必要的事实信息 | 上下文管理、RAG、记忆注入、Token 优化 |
| Harness Engineering | 执行——整个系统怎么防崩、怎么量化、怎么持续运转 | 长链路任务中的持续正确、偏差纠正、故障恢复 | 文件系统、沙箱、约束执行、熵管理、反馈回路 |
适用场景递进：
- 简单任务 → Prompt Engineering 最重要
- 依赖外部知识的任务 → Context Engineering 关键
- 长链路、可执行、低容错的商业场景 → Harness Engineering 决定成败
三、Harness 核心组件（模型做不到 → Harness 来补）
| 模型做不到 | Harness 怎么补 | 核心组件 |
|---|---|---|
| 记住多轮对话历史 | 维护对话历史，每次请求时拼进上下文 | 记忆系统 |
| 执行代码、跑命令 | 提供 Bash + 代码执行环境 | 通用执行环境 |
| 获取实时信息 | Web Search、MCP 工具 | 外部知识获取 |
| 操作文件和环境 | 文件系统抽象 + Git 版本控制 | 文件系统 |
| 知道自己做对了没有 | 沙箱环境 + 测试工具 + 浏览器自动化 | 验证闭环 |
| 在长任务中保持连贯 | 上下文压缩、记忆文件、进度追踪 | 上下文管理 |
四、Harness 六层架构（核心框架）
| 层级 | 名称 | 解决什么问题 | 关键设计 | 类比（新手员工工作环境） |
|---|---|---|---|---|
| L1 | 信息边界层 | Agent 该知道什么、不该知道什么 | 定义角色与目标，裁剪无关信息，结构化组织任务状态 | 岗位说明书 |
| L2 | 工具系统层 | Agent 怎么跟外部世界交互 | 工具的选拔、调用时机、结果的提炼与反馈 | 办公工具 |
| L3 | 执行编排层 | 多步骤任务怎么串起来 | 让模型走完"理解目标→判断信息→分析→生成→检查"的完整轨道 | 标准操作流程 |
| L4 | 记忆与状态层 | 长任务中间结果怎么管 | 独立管理当前任务状态、中间产物和长期记忆 | 项目管理系统和笔记本 |
| L5 | 评估与观测层 | Agent 怎么知道自己做对了没有 | 建立独立于生成过程的验证机制，让 Agent 具备"自知之明" | 质检流程 |
| L6 | 约束、校验与恢复层 | 出错了怎么办 | 预设规则拦截错误，失败时提供重试或回滚机制 | 红线规则和应急预案 |
启动建议：不要试图一开始就搭齐六层。从 L1（信息边界） 和 L6（约束与恢复） 入手，投入产出比最高。
五、为什么瓶颈不在模型而在 Harness？
关键实验证据
| 来源 | 实验 | 结果 |
|---|---|---|
| Can.ac | 同一模型，只换文件编辑接口的调用方式 | 编码基准分数从 6.7% → 68.3%（10倍提升） |
| LangChain | 优化 Agent 运行环境（文档组织、验证回路、追踪系统），模型不变 | Terminal Bench 2.0 排名从全球第30 → 第5，得分 52.8% → 66.5% |
重要发现：Model-Harness 耦合问题
"The best harness for your task is not necessarily the one a model was post-trained with."
当前 Agent 产品（Claude Code、Codex）是模型和 Harness 一起训练的，导致过拟合——换了工具逻辑后模型表现会变差。Opus 在 Claude Code 的 Harness 下得分，远低于在其他 Harness 中的得分。
六、上下文管理：40% 阈值法则
| 区间 | 占比 | 表现 |
|---|---|---|
| Smart Zone | 0 ~ 40% | 推理聚焦、工具调用准确、代码质量高 |
| Dumb Zone | 超过 ~40% | 幻觉增多、兜圈子、格式混乱、低质量代码 |
工程实践：在生产环境中监控上下文利用率是第一优先级。建议设置 40% 阈值告警，超过即触发上下文压缩或任务交接。
Anthropic 的解决方案：Context Resets（上下文重置）
不是压缩，而是重启：
- 上下文接近饱和时，结构化提取当前任务状态、已完成工作、待办事项
- 启动全新的"干净" Agent
- 新 Agent 从干净状态继续工作
类比：程序内存泄漏时的解法——不去手动释放每个内存块，而是重启进程，从检查点恢复状态。
七、从零搭建 Harness：P0/P1/P2 行动清单
P0：立即可以做（投入产出比最高）
| 行动 | 为什么 | 参考实践 |
|---|---|---|
创建 AGENTS.md 并持续维护 | Agent 每次启动自动加载，犯错就更新，形成反馈循环 | Hashimoto：每一行对应一个历史失败案例 |
| 构建自定义 Linter + 修复指令 | 错误消息里直接告诉 Agent 怎么改，纠错的同时在"教" | OpenAI 的 Linter 报错自带修复方法 |
| 把团队知识放进仓库 | 写在 Slack/Wiki/Docs 里的知识对 Agent 等于不存在 | OpenAI 以仓库为唯一事实源 |
常见误区：
AGENTS.md不要当"超级 System Prompt"来写。正确做法——只当目录用（约 100 行），详细规则放在子文档中按需加载（渐进式披露）。
P1：P0 之后考虑
| 行动 | 为什么 | 参考实践 |
|---|---|---|
| 分层管理上下文 | 不要把所有东西塞进一个文件，渐进式披露 | OpenAI AGENTS.md 当目录用 |
| 建立进度文件和功能列表 | JSON 格式追踪功能状态，Agent 不太会乱改结构化数据 | Anthropic 初始化 Agent + 编码 Agent 两阶段 |
| 给 Agent 端到端验证能力 | 浏览器自动化让 Agent 能像用户一样验证功能 | Anthropic 用 Playwright/Puppeteer MCP |
| 控制上下文利用率 | 尽量不超过 40%，增量执行 | Dex Horthy 的 Smart Zone / Dumb Zone |
P2：有余力再考虑
| 行动 | 为什么 | 参考实践 |
|---|---|---|
| Agent 专业化分工 | 每个 Agent 携带更少无关信息，留在 Smart Zone | Carlini 的去重/优化/文档 Agent |
| 定期垃圾回收 | 确保清理速度跟得上生成速度 | OpenAI 的后台清理 Agent |
| 可观测性集成 | 把"性能优化"从玄学变成可度量的工作 | OpenAI 接入 Chrome DevTools |
八、Harness 成熟度五阶段
| 阶段 | 特征 | 工程师角色 |
|---|---|---|
| Level 0：无 Harness | 直接给 Agent prompt，无结构化约束 | 手动写代码 + 偶尔使用 AI |
| Level 1：基础约束 | AGENTS.md + 基础 Linter + 手动测试 | 主要写代码，AI 辅助 |
| Level 2：反馈回路 | CI/CD 集成 + 自动化测试 + 进度追踪 | 规划 + 审查为主 |
| Level 3：专业化 Agent | 多 Agent 分工 + 分层上下文 + 持久化记忆 | 环境设计 + 管理为主 |
| Level 4：自治循环 | 无人值守并行化 + 自动化熵管理 + 自修复 | 架构师 + 质量把关者 |
九、一线团队实战案例
9.1 OpenAI：3人、5个月、100万行、0手写代码
| 指标 | 数值 |
|---|---|
| 团队规模 | 3 → 7 人 |
| 代码规模 | ~100 万行 |
| 手写代码 | 0 行（设计约束） |
| 合并 PR 数 | ~1,500 个 |
| 效率提升 | ~10 倍 |
五大方法论：
| 方法论 | 核心做法 | 关键洞察 |
|---|---|---|
| 地图式文档 | AGENTS.md 仅 ~100 行，当目录用，指向 docs/ 深层文档 | 渐进式披露：给 Agent 一张地图，不是千页手册 |
| 机械化约束 | 自定义 Linter + 结构测试，报错自带修复方法 | "If it cannot be enforced mechanically, agents will deviate." |
| 可观测性给 Agent 看 | Chrome DevTools Protocol 接入 Agent 运行时 | Agent 能自己抓 DOM 快照、截图、测量性能 |
| 主动对抗熵 | 后台 Agent 定期扫描，自动提交清理 PR | 熵不会自己消失，清理速度必须跟上生成速度 |
| 仓库即唯一事实源 | 所有团队知识版本控制在仓库中 | Slack 里的知识对 Agent 等于不存在 |
9.2 Anthropic：GAN 式三智能体架构
Planner（规划者）→ Generator（执行者）⇄ Evaluator（评估者）| 角色 | 职责 |
|---|---|
| Planner | 1-4 句话产品描述 → 完整产品规格，"范围上要大胆" |
| Generator | 按功能逐个 Sprint 执行，每个有明确完成标准 |
| Evaluator | 用 Playwright MCP 实际点击运行中的应用，多维度打分 |
解决两个核心问题：
| 问题 | 表现 | 解法 |
|---|---|---|
| 上下文焦虑 | Sonnet 4.5 上下文快满时草草收尾 | Context resets + 结构化交接（非压缩） |
| 自我评价偏差 | Agent 自信满满，实际质量一般 | 生成和评估交给两个独立 Agent |
关键发现：模型从 Sonnet 4.5 换成 Opus 4.6 后，Sprint 机制可完全移除，Evaluator 从每轮检查 → 最终只检查一次。
Anthropic 精辟总结："Every component in a harness encodes an assumption about what the model can't do on its own, and those assumptions are worth stress testing."
模型越强，Harness 设计空间转移而非缩小——需要定期简化 Harness，移除已冗余的保护机制。
9.3 Stripe：每周 1300+ PR，全程无人值守
| 组件 | 作用 | 关键设计 |
|---|---|---|
| Devbox | 开发环境 | AWS EC2 预装源码和服务，预热池分配，启动 ~10 秒，"牲口不是宠物" |
| 编排状态机 | 流程控制 | 混合确定性节点（lint、push）和 Agent 节点（实现功能、修 CI） |
| Toolshed MCP | 工具服务 | 集中式 MCP 服务，近 500 个工具，每个 Minion 获筛选子集 |
| 反馈回路 | 质量保障 | Pre-push hook 秒级修 lint；推送后最多 2 轮 CI（300 万+ 测试） |
核心理念："What's good for humans is good for agents."——为人类工程师投资的 Devbox、工具链和开发者体验，在 Agent 上直接产生回报。
9.4 Mitchell Hashimoto：单 Agent 深度参与模式
| 步骤 | 名称 | 核心做法 |
|---|---|---|
| 1 | 放弃聊天模式 | 让 Agent 在能读文件、跑程序、发 HTTP 请求的环境里直接干活 |
| 2 | 复现自己的工作 | 每件事做两次——一次自己做，一次让 Agent 做（"痛苦至极"） |
| 3 | 下班前启动 Agent | 每天最后 30 分钟布置任务：深度调研、模糊探索、Issue 分拣 |
| 4 | 外包确定性任务 | 挑出 Agent 几乎一定能做好的任务后台跑着，关掉桌面通知 |
| 5 | 工程化 Harness | 每当 Agent 犯错，就工程化一个解决方案让它永远不再犯 |
| 6 | 始终有 Agent 在跑 | 目标 10-20% 工作时间有后台 Agent 运行 |
AGENTS.md的正确用法：Ghostty 项目的AGENTS.md，每一行都对应一个过去的 Agent 失败案例——不是静态文档，而是持续积累的防错系统。
9.5 Birgitta Böckeler：系统化梳理与前瞻判断
Harness 组件三类归一：
| 归类 | 关注点 | 典型实践 |
|---|---|---|
| Context Engineering | 管理 Agent 看到什么、什么时候看到 | 巨大 AGENTS.md → 入口文件 + 分层文档 |
| Architectural Constraints | 确保 Agent 不跑偏 | 自定义 Linter、结构测试、LLM Agent 充当约束 |
| Garbage Collection | 对抗熵积累 | 定期运行清理 Agent 扫描不一致和违规 |
三个前瞻性判断：
- Harness 将成为新的服务模板——像今天从服务模板实例化新服务一样
- 棕地项目改造是最大挑战——所有公开案例都是绿地项目；提出 "Ambient Affordances" 概念：环境本身的结构特性（类型系统、模块边界、框架抽象）决定 Harness 能做多好
- 功能验证体系几乎缺席——"用 AI 生成的测试来验证 AI 生成的代码，本质上是用同一双眼睛检查自己的作业"
十、面试高频问题速查
基础概念
| 问题 | 核心回答 |
|---|---|
| Harness 是什么？ | 模型之外的一切。Agent = Model + Harness。 |
| 三层关系？ | 嵌套：Prompt ⊂ Context ⊂ Harness。分别解决表达、信息、执行。 |
| 为什么瓶颈不在模型？ | Can.ac 实验：同一模型换接口格式，6.7% → 68.3%。基础设施质量决定模型能力的实际发挥。 |
架构设计
| 问题 | 核心回答 |
|---|---|
| 六层架构？ | L1 信息边界 → L2 工具系统 → L3 执行编排 → L4 记忆与状态 → L5 评估与观测 → L6 约束校验与恢复 |
| 上下文管理经验法则？ | 利用率控制在 40% 以内。超过后质量明显下降。策略是压缩或交接，不是继续塞信息。 |
| 单 Agent 还是多 Agent？ | 规模决定。小项目单 Agent 够用（Hashimoto），大项目几乎必然需要专业化分工（Carlini 16 个并行 Agent）。 |
实战方案
| 问题 | 核心回答 |
|---|---|
| OpenAI 实践核心？ | 五大方法论：地图式文档、机械化约束、可观测性接入、熵管理、仓库即事实源 |
| Anthropic 解决上下文焦虑？ | Context resets：不压缩，启动全新干净 Agent，结构化交接文档恢复状态。类比重启进程解决内存泄漏。 |
| 从零搭 Harness 先做什么？ | P0：AGENTS.md + 自定义 Linter + 团队知识仓库化 |
十一、尚未解决的问题（展现思考深度）
| 问题 | 现状 | 关键概念 |
|---|---|---|
| 棕地项目怎么改造？ | 所有公开案例全是绿地项目，零方法论 | "Ambient Affordances"：环境结构特性决定 Harness 上限 |
| 怎么验证 Agent 做对了事？ | 擅长"约束不做错事"，"验证做对了事"远未解决 | 用 AI 测试验证 AI 代码 = "用同一双眼睛检查自己的作业" |
| AI 生成代码的长期可维护性？ | LLM 经常重新实现已有功能，长期效果未知 | Greg Brockman 提出，至今无人回答 |
| Harness 该做厚还是做薄？ | Manus 五次重写越做越简单 vs OpenAI 五个月越做越复杂 | 场景决定：通用产品追求最小化，特定产品可高度定制；模型变强后应定期简化 |
| 单 Agent 还是多 Agent？ | Hashimoto 坚持单 Agent vs Carlini 用 16 个并行 Agent | 规模决定 |
十二、一句话总结
承认模型有边界，然后把边界之外的需求一个个工程化地补上。
与其纠结选哪个模型，不如先把 Harness 搭好。
附录：关键引用原文
| 来源 | 金句 |
|---|---|
| OpenAI | "If it cannot be enforced mechanically, agents will deviate." |
| Anthropic | "Every component in a harness encodes an assumption about what the model can't do on its own, and those assumptions are worth stress testing." |
| Anthropic | "The space of interesting harness combinations doesn't shrink as models improve. Instead, it moves." |
| Stripe | "What's good for humans is good for agents." |
| Carlini | "I must constantly remind myself: I am writing this test framework for Claude, not for myself." |
笔记整理完成。核心框架：六层架构 + 40% 上下文阈值 + P0/P1/P2 行动清单 + 一线团队五大案例。